How to link your code and zk together to make a new zk.exe


Note: The features described in this document are only supported by the
pro version of zk.

This document describes how to link your code and zk together to make
a new zk.  The advantage of doing so is that you can then call your
compiled functions from the interpreted code you input to zk.  That
lets your compiled functions run at full compiled speed instead of
interpreted speed.  Compiled code is a lot faster than interpreted
code, especially when it involves loops with large numbers of
iterations.

You may ask why bother to use an interpreter at all if compiled code
is so much faster.  The advantage of interpreted code is that you don't
have to wait for it to compile before you use it.  You can type in
command lines and see them execute immediately.  Thus, an interpreter
supports exploratory programming, which you do when you are starting to
test your ideas for a new program design, but before you get into the
formal design phase.  Designing software without doing any exploratory
programming often leads to poor designs requiring costly rework.

Compiling your code and linking it and zk together into a new zk.exe
is an effective way to add new powerful features to zk.  You will
probably want to compile and link repeatedly, as you add new features
to zk and debug them.  To compile and link repeatedly, you need a
makefile or batch file, to avoid typing the same commands repeatedly.

To get started writing your makefile or batch file, an example batch
file, linkex.bat, is supplied, along with a corresponding example c++
source file, linkex.zk, which gets compiled and linked with zk by
linkex.bat to make a new zk.exe.  The first thing linkex.bat does is
to use zk prep to preprocess linkex.zk to create linkex.cpp.  The
filename extension ".zk" indicates that the language used is the zk
extended version of c++, which gets converted to ordinary c++ in
linkex.cpp.

You need to use zk prep even if you don't use the zk extensions to
c++, because in addition to preprocessing the code, zk prep adds
information which will be used when interpreted code calls compiled
code.

If this sounds complicated, don't worry about it, just use linkex.bat
and linkex.zk as described below, and it will soon seem trivial.

First, you might want to make a new directory where you will build
your new version of zk.exe, and leave the old version where it is.
The simplest way is to just copy all the files, *.*, from the old
directory to the new one.  Go to that directory and edit linkex.zk,
making a minor change to some of the text it outputs, so you will
be able to see that the new version is your version.  Then run
linkex.bat to build the new version, and when it's done, run it, by
typing "zk" at the operating system command line, and then on the
zk command line, type "linkex()" to call the linkex function, to
see that the output is from the change you made.

Having successfully made a minor change to linkex.zk and seen it run,
you are now ready to proceed with adding your own code.  First, decide
whether you want to use more than one new source file, and whether you
want to use a batch file like linkex.bat or a makefile.  Create your
new batch file or makefile by copying the commands from linkex.bat and
modifying them as needed, as indicated by the comments.  Or you can
start more gradually, by gradually making changes to linkex.zk, to see
each change work in zk.exe before proceeding, and then gradually add
more source files, as explained in the comments in linkex.zk.